Usenet 1993 July/InfoMagic USENET CD-ROM July 1993.ISO/sources/unix/volume23/sc6.8/part01

Internet Message Format | 1990-10-09 | 52.7 KB

Subject:  v23i021:  The SC Spreadsheet, release 6.8, Part01/06
Newsgroups: comp.sources.unix
Approved: [e-mail]
X-Checksum-Snefru: 734e5634 f01da32e 5cdd0a22 2f00bb17

Submitted-by: Jeff Buhrt <sawmill!buhrt>
Posting-number: Volume 23, Issue 21
Archive-name: sc6.8/part01

This is a much modified version of the public domain spread sheet sc,
posted several years ago by Mark Weiser as vc, originally by James
Gosling.

Starting 4/4/90: (I will be maintaining Sc for a while at least, Robert
Bond has been very busy lately) Sc is not a product of Grauel Enterprises,
Inc.  It is supplied as is with no warranty, express or implied, as a
service to Usenet readers.  It is not copyrighted, either.  Have at it.
                    Jeff Buhrt
                    Grauel Enterprises, Inc.
    {pur-phy (aka: newton.physics.purdue.edu), sequent}!sawmill!buhrt

#! /bin/sh
# This is a shell archive.  Remove anything before this line, then feed it
# into a shell via "sh file" or similar.  To overwrite existing files,
# type "sh file -c".
# The tool that generated this appeared in the comp.sources.unix newsgroup;
# send mail to [e-mail] if you want that tool.
# Contents:  README MANIFEST sc.doc
# Wrapped by [e-mail] on Fri Jul 13 15:24:17 1990
PATH=/bin:/usr/bin:/usr/ucb ; export PATH
echo If this archive is complete, you will see the following message:
echo '          "shar: End of archive 1 (of 6)."'
if test -f 'README' -a "${1}" != "-c" ; then
  echo shar: Will not clobber existing file \"'README'\"
else
  echo shar: Extracting \"'README'\" \(3004 characters\)
  sed "s/^X//" >'README' <<'END_OF_FILE'
XThis is a much modified version of the public domain spread sheet sc,
Xposted several years ago by Mark Weiser as vc, originally by James Gosling.
X
XChanges since my last version (5.1) are detailed at great length :-)
Xin CHANGES (sequent!rgb (Robert Bond)).
X
XWhen you get it built, try "sc tutorial.sc" for a simple introduction
Xto the basic commands.
X
XA new input parser program (psc) has been included.  This program
Xformats ascii files for use in the spread sheet.  If you don't have
Xgetopts, there is a public domain version by Henry Spencer hidden away
Xin the VMS_NOTES file.
X
XI have modified the makefile to make it easy for you to call the
Xprogram what you want (I saw at least five different names in
Xcorrespondence and on the net).  Just change "name=sc" and "NAME=SC" to
X"name=myfavoritename" and "NAME=MYFAVORITENAME" and try "make
Xmyfavoritename".
X
XSimilarly, you can make the documentation with "make myfavoritename.man".
X"make install" will make and install the code in EXDIR.  The
Xinstallation steps and documentation all key off of the name.  The
Xmakefile even changes the name in the nroffable man page.  If you don't
Xhave nroff, you will have to change sc.man yourself.
X
XThis release has been tested against a Sequent S81 running DYNIX 3.0.14
X(BSD 4.2) and an ICM-3216 with system V.3.  The ICM has a National Semi
X32016.  Just check the makefile for the system flags.   I have heard
Xreports of lots of other machines that work. If you have problems with
Xlex.c, and don't care about arrow keys, define SIMPLE (-DSIMPLE in the
Xmakefile).  SIMPLE causes the arrow keys to not be used.
X
XGuidelines for Hackers:
X
XIf you want to send changes you have made to SC, please feel free to do
Xso.  If they work :-) and seem worthwhile, I'll put them in.  Please
Xrefrain from wholesale "style" or "cleanup" changes.  It is easy to add
Xyour changes but it makes it hard to merge in the next guy's stuff if
Xhe used the release as a base.  Leave my $Revision:  identifiers alone-
Xthey help me track what you used as a base.  If you check the code into
Xrcs, delete the "$"s on the Revison lines before you do.
X
XYou may not like 4 space indenting and curly braces on the "if" line,
Xbut your code will look like that before it leaves my hands so you may
Xas well abide by the style in the code when you make your changes.  I
Xhave also been known to break things trying to make them look "right".
XIf you do string functions, please, PLEASE pay attention to null
Xpointers, use xmalloc and xfree, and xfree those arguments.  And
Xdon't forget to document your changes in both help.c and sc.doc.
X
XDisclaimer:
X
XStarting 4/4/90: (I will be maintaining Sc for a while at least,
X    Robert Bond has been very busy lately)
XSc is not a product of Grauel Enterprises, Inc.  It is supplied as
Xis with no warranty, express or implied, as a service to Usenet readers.
XIt is not copyrighted, either.  Have at it.
X
X                    Jeff Buhrt
X                    Grauel Enterprises, Inc.
X    {pur-phy (aka: newton.physics.purdue.edu), sequent}!sawmill!buhrt
END_OF_FILE
  if test 3004 -ne `wc -c <'README'`; then
    echo shar: \"'README'\" unpacked with wrong size!
  fi
  # end of 'README'
fi
if test -f 'MANIFEST' -a "${1}" != "-c" ; then
  echo shar: Will not clobber existing file \"'MANIFEST'\"
else
  echo shar: Extracting \"'MANIFEST'\" \(983 characters\)
  sed "s/^X//" >'MANIFEST' <<'END_OF_FILE'
X   File Name        Archive #    Description
X----------------------------------------------------------
XREADME                     1
XMANIFEST                   1    This shipping list
XCHANGES                    5
XMakefile                   6
XTODO                       6
XVMS_NOTES                  6
Xcmds.c                     4
Xcrypt.c                    6
Xeres.sed                   5
Xgram.y                     5
Xhelp.c                     3
Xinterp.c                   2
Xlex.c                      4
Xpsc.c                      4
Xpsc.doc                    5
Xrange.c                    5
Xsc.c                       3
Xsc.doc                     1
Xsc.h                       5
Xsc6.8p1.hdr                2
Xsc6.8p2.hdr                6
Xsc6.8p3.hdr                6
Xsc6.8p4.hdr                6
Xsres.sed                   2
Xtutorial.sc                6
Xversion.c                  5
Xvi.c                       5
Xvmtbl.c                    5
Xxmalloc.c                  4
END_OF_FILE
  if test 983 -ne `wc -c <'MANIFEST'`; then
    echo shar: \"'MANIFEST'\" unpacked with wrong size!
  fi
  # end of 'MANIFEST'
fi
if test -f 'sc.doc' -a "${1}" != "-c" ; then
  echo shar: Will not clobber existing file \"'sc.doc'\"
else
  echo shar: Extracting \"'sc.doc'\" \(45229 characters\)
  sed "s/^X//" >'sc.doc' <<'END_OF_FILE'
X.\" Warning:  The string "pname" is converted to the true program name
X.\" by the makefile, throughout this document.
X.\"
X.\" Warning:  The order of presentation of commands largely matches the
X.\" help screen built into the program.
X.\"
X.\" Conventions:
X.\" - pname italicized and never uppercased (it's a proper name).
X.\" - Refer to lists of commands in the same order as introduced.
X.\" - Command and function names bold when introduced, italicized in all
X.\"   other places if possible, or in `` '' if not.
X.\" - Cell names italicized except when used in expressions; row numbers
X.\"   and column names not italicized.
X.\" - Use `` '' rather than " " except referring to literal input or output.
X.\" - TPs use default indent except for function names, then 18.
X.\" - Smallify uppercase strings.
X.\" - Avoid passive voice and third person.
X.\" $Revision: 6.8 $
X.\"
X.TH PNAME 1
X.SH NAME
Xpname \- spreadsheet calculator
X.SH SYNOPSIS
X.B pname
X[
X.B -c
X]
X[
X.B -m
X]
X[
X.B -n
X]
X[
X.B -r
X]
X[
X.B -x
X]
X[
X.I file
X]
X.\" ==========
X.SH DESCRIPTION
XThe spreadsheet calculator
X.I pname
Xis based on rectangular tables much like a financial spreadsheet.
XWhen invoked it presents you with a table
Xorganized as rows and columns of cells.
XIf invoked without a
X.I file
Xargument, the table is initially empty.
XOtherwise
X.I file
Xis read in (see the
X.I Get
Xcommand below).
XEach cell may have associated with it
Xa numeric value,
Xa label string,
Xand/or an expression (formula)
Xwhich evaluates to a numeric value or label string,
Xoften based on other cell values.
X.\" ----------
X.PP
XOptions are:
X.\" ----------
X.TP
X.B \-c
XStart the program with the recalculation being done in column order.
X.\" ----------
X.TP
X.B \-m
XStart the program with automatic recalculation disabled.
XThe spreadsheet will be recalculated only when the ``@'' command is used.
X.\" ----------
X.TP
X.B \-n
XStart the program in quick numeric entry mode (see below).
X.\" ----------
X.TP
X.B \-r
XStart the program with the recalculation being done in row
Xorder (default option).
X.\" ----------
X.TP
X.B \-x
XCause the
X.I Get
Xand
X.I Put
Xcommands (see below) to encrypt and decrypt data files.
X.\" ----------
X.PP
XAll of these options can be changed with the
X.I ^T
Xand
X.I S
Xcommands (see below) while
X.I pname
Xis running.  Options specified when
X.I pname
Xis invoked
Xoverride options saved in the data file.
X.\" ==========
X.SS "General Information"
X.\" ----------
XThe screen is divided into four regions.
XThe top line is for entering commands and displaying cell values.
XThe second line is for messages from
X.IR pname .
XThe third line and the first four columns show the column and row numbers,
Xfrom which are derived cell addresses, e.g.
X.I A0
Xfor the cell in column A, row 0.
XNote that column names are case-insensitive: you can enter
X.I A0
Xor
X.IR a0 .
X.\" ----------
X.PP
XThe rest of the screen forms a window looking at a portion of the table.
XThe total number of display rows and columns available,
Xhence the number of table rows and columns displayed,
Xis set by
X.IR curses (3)
Xand may be overridden by setting the
X.SM LINES
Xand
X.SM COLUMNS
Xenvironment variables, respectively.
X.\" ----------
X.PP
XThe screen has two cursors:
Xa cell cursor, indicated by a highlighted cell and a ``<'' on the screen,
Xand a character cursor, indicated by the terminal's hardware cursor.
XThe cell and character cursors are often the same.
XThey differ when you type a command on the top line.
X.\" ----------
X.PP
XIf a cell's numeric value is wider than the column width (see the
X.I f
Xcommand), the cell is filled with asterisks.
XIf a cell's label string is wider than the column width,
Xit is truncated at the start of the next non-blank cell in the row, if any.
X.\" ----------
X.PP
XCursor control commands and row and column commands
Xcan be prefixed by a numeric argument
Xwhich indicates how many times the command is to be executed.
XYou can type
X.I ^U
Xbefore a repeat count if quick numeric entry mode is enabled
Xor if the number is to be entered
Xwhile the character cursor is on the top line.
X.\" ----------
X.PP
XCommands which use the terminal's control key, such as
X.IR ^N ,
Xwork both when a command is being typed and when in normal mode.
X.\" ==========
X.SS "Changing Options"
X.\" ----------
X\0 \" exactly one blank line (hard to get)
X.PD 0
X.TP
X.BI ^T o
XToggle options.
XThis command allows you to switch the state of one option selected by
X.IR o .
XA small menu lists the choices for
X.I o
Xwhen you type
X.IR ^T .
XThe options selected are saved when the data and formulas are saved
Xso that you will have the same setup next time you enter the
Xspreadsheet.
X.PD
X.RS
X.\" ----------
X.TP
X.B a
XAutomatic Recalculation.
XWhen set, each change in the spreadsheet causes the entire spreadsheet
Xbe recalculated.  Normally this is not noticeable, but for very large
Xspreadsheets, it may be faster to clear automatic recalculation mode and
Xupdate the spreadsheet via explicit ``@'' commands.  Default is
Xautomatic recalculation on.
X.\" ----------
X.TP
X.B c
XCurrent cell highlighting.
XIf enabled, the current cell is highlighted
X(using the terminal's standout mode, if available)
Xin addition to being marked by the cell cursor.
X.\" ----------
X.TP
X.B e
XExternal function execution.
XWhen disabled, external functions (see
X.IR @ext ()
Xbelow) are not called.
XThis saves a lot of time at each screen update.
XExternal functions are disabled by default.
XIf disabled, and external functions are used anywhere,
Xa warning is printed each time the screen is updated,
Xand the result of
X.IR @ext ()
Xis the value from the previous call, if any, or a null string.
X.\" ----------
X.TP
X.B n
XQuick numeric entry.
XIf enabled,
Xa typed digit is assumed to be
Xthe start of a numeric value for the current cell,
Xnot a repeat count, unless preceded by
X.IR ^U .
X.\" ----------
X.TP
X.B t
XTop line display.
XIf enabled,
Xthe name and value of the current cell is displayed on the top line.
XIf there is an associated label string,
Xthe first character of the string value
Xis ``<'' for a leftstring or ``>'' for a rightstring (see below),
Xfollowed by "\fIstring\fP" for a constant string
Xor
X.RI { expr }
Xfor a string expression.
XIf the cell has a numeric value,
Xit follows as
X.RI [ value ],
Xwhich may be a constant or expression.
X.\" ----------
X.TP
X.B x
XEncryption.
XSee the
X.B \-x
Xoption.
X.\" ----------
X.TP
X.B $
XDollar prescale.
XIf enabled, all numeric
X.B constants
X(not expressions) which you enter are multipled by 0.01
Xso you don't have to keep typing the decimal point
Xif you enter lots of dollar figures.
X.RE
X.\" ----------
X\0 \" exactly one blank line (hard to get)
X.PD 0
X.TP
X.B S
XSet options.  This command allows you to set various options.
XA small menu lists the options that cannot be changed through
X.I ^T
Xabove.
X.PD
X.RS
X.TP
X.BR byrows /  bycols
XSpecify the order cell evaluation when updating.  These options also affect
Xthe order in which cells are filled (see
X.IR /f )
Xand whether a row or column is cleared by an
X.I x
Xcommand.
X.TP
X.BI iterations =n
XSet the maximum number of recalculations before
Xthe screen is displayed again.
X.I Iterations
Xis set to 10 by default.
X.TP
X.BI tblstyle =s
XControl the output of the
X.I T
Xcommand.
X.I s
Xcan be:
X.B 0
X(default) to give colon delimited fields, with no
X.I tbl
Xcontrol lines;
X.B tbl
Xto give colon delimited fields, with
X.IR tbl (1)
Xcontrol lines;
X.B latex
Xto give a
X.I LaTeX
Xtabular environment; and
X.B tex
Xto give a
X.I TeX
Xsimple tabbed alignment with ampersands as delimiters.
X.PP
XOther
X.I Set
Xoptions are normally used only in
X.I pname
Xdata files since they are available through
X.IR ^T .
XYou can also use them interactively
X.TP
X.BR autocalc / !autocalc
XSet/clear auto recalculation mode.
X.TP
X.BR numeric / !numeric
XSet/clear numeric mode.
X.TP
X.BR prescale / !prescale
XSet/clear numeric prescale mode.
X.TP
X.BR extfun / !extfun
XEnable/disable external functions.
X.TP
X.BR cellcur / !cellcur
XSet/clear current cell highlighting mode.
X.TP
X.BR toprow /  !toprow
XSet/clear top row display mode.
X.RE
X.\" ==========
X.SS "Cursor Control Commands"
X.\" ----------
X\0 \" exactly one blank line (hard to get)
X.PD 0
X.TP
X.B ^P
XMove the cell cursor up to the previous row.
X.PD
X.\" ----------
X.TP
X.B ^N
XMove the cell cursor down to the next row.
X.\" ----------
X.TP
X.B ^B
XMove the cell cursor backward one column.
X.\" ----------
X.TP
X.B ^F
XMove the cell cursor forward one column.
X.\" ----------
X.TP
X.B "h, j, k, l"
XIf the character cursor is not on the top line, these are alternate,
X.IR vi -compatible
Xcell cursor controls (left, down, up, right).
X.\" ----------
X.TP
X.B ^H
XIf the character cursor is not on the top line,
X.I ^H
Xis the same as
X.IR ^B .
X.\" ----------
X.TP
X.B SPACE
XIf the character cursor is not on the top line,
Xthe space bar is the same as
X.IR ^F .
X.\" ----------
X.TP
X.B TAB
XIf the character cursor is on the top line,
X.SM TAB
Xstarts a range (see below).
XOtherwise, it is the same as
X.IR ^F .
X.\" ----------
X.TP
X.B "Arrow Keys"
XThe terminal's arrow keys provide another alternate set of cell cursor controls
Xif they exist and are supported in the appropriate
X.I termcap
Xentry.
XSome terminals have arrow keys which conflict with other control key codes.
XFor example, a terminal might send
X.I ^H
Xwhen the back arrow key is pressed.
XIn these cases, the conflicting arrow key performs the same function
Xas the key combination it mimics.
X.\" ----------
X.TP
X.B ^
XMove the cell cursor up to row 0 of the current column.
X.\" ----------
X.TP
X.B #
XMove the cell cursor down to the last valid row of the current column.
X.\" ----------
X.TP
X.B 0
XMove the cell cursor backward to column A of the current row.
XThis command must be prefixed with
X.I ^U
Xif quick numeric entry mode is enabled.
X.\" ----------
X.TP
X.B $
XMove the cell cursor forward to the last valid column of the current row.
X.\" ----------
X.TP
X.B b
XScan the cursor backward (left and up) to the previous valid cell.
X.\" ----------
X.TP
X.B w
XScan the cursor forward (right and down) to the next valid cell.
X.\" ----------
X.TP
X.BI ^E d
XGo to end of range.
XFollow
X.I ^E
Xby a direction indicator such as
X.I ^P
Xor
X.IR j .
XIf the cell cursor starts on a non-blank cell,
Xit goes in the indicated direction until the last non-blank adjacent cell.
XIf the cell cursor starts on a blank cell,
Xit goes in the indicated direction until the first non-blank cell.
XThis command is useful when specifying ranges of adjacent cells (see below),
Xespecially when the range is bigger than the visible window.
X.\" ----------
X.TP
X.B g
XGo to a cell.
X.I pname
Xprompts for a cell's name, a regular expression surrounded by
Xquotes, or a number.
XIf a cell's name such as
X.I ae122
Xor a the name of a defined range is given, the cell cursor goes
Xdirectly to that cell.
XIf a quoted regular expression such as "
X.I Tax Table
X" or "
X.I ^Jan [0-9]*$
X" is given,
X.I pname
Xsearches for a cell containing a string matching the regular
Xexpression.
XSee
X.I regex(3)
Xor
X.I ed(1)
Xfor more details on the form of regular
Xexpressions.
XIf a number is given,
X.I pname
Xwill search for a cell containing that number.
XSearches for either strings or numbers proceed forward from the
Xcurrent cell, wrapping back to a0 at the end of the table, and
Xterminate at the current cell if the string or number is not found.
XThe last
X.I g
Xcommand is saved, and can be re-issued by entering
X.IR g<return> .
X.\" ==========
X.SS "Cell Entry and Editing Commands"
X.\" ----------
XCells can contain both a numeric value and a string value.
XEither value can be the result of an expression,
Xbut not both at once,
Xi.e. each cell can have only one expression associated with it.
XEntering a valid numeric expression
Xalters the cell's previous numeric value, if any,
Xand replaces the cell's previous string expression, if any,
Xleaving only the previously computed constant label string.
XLikewise, entering a valid string expression
Xalters the cell's the previous label string, if any,
Xand replaces the cell's previous numeric expression, if any,
Xleaving only the previously computed constant numeric value.
X.TP
X.B =
XEnter a numeric constant or expression into the current cell.
X.I pname
Xprompts for the expression on the top line.
XThe usual way to enter a number into a cell is to type ``='',
Xthen enter the number in response to the prompt on the top line.
XThe quick numeric entry option, enabled through the
X.B \-n
Xoption or
X.I ^T
Xcommand, shows the prompt when you enter the first digit of a number
X(you can skip typing ``='').
X.\" ----------
X.TP
X.B <
XEnter a label string into the current cell
Xto be flushed left against the left edge of the cell.
X.\" ----------
X.IP \fB"\fP
X.PD 0
X.TP
X.B >
XEnter a label string into the current cell
Xto be flushed right against the right edge of the cell.
X.PD
X.\" ----------
X.PP
XStrings you enter must start with ".
XYou can leave off the trailing " and
X.I pname
Xwill add it for you.
XYou can also enter a string expression
Xby backspacing over the opening " in the prompt.
X.\" ----------
X.TP
X.B e
XEdit the value associated with the current cell.
XThis is identical to ``=''
Xexcept that the command line starts out containing
Xthe old numeric value or expression associated with the cell.
X.\" ----------
X.TP
X.B E
XEdit the string associated with the current cell.
XThis is identical to ``<'', ``"'', or ``>''
Xexcept that the command line starts out containing
Xthe old string value or expression associated with the cell.
X.\" ----------
X.PP
XTo enter and edit a cell's number part, use the ``='' and
X.I e
Xcommands.
XTo enter and edit a cell's string part, use the ``<'', ``"'', ``>'', and
X.I E
Xcommands.
XSee the sections below on numeric and string expressions for more information.
X.\" ----------
X.TP
X.B x
XClear the current cell.
XDeletes the numeric value, label string, and/or numeric or string expression.
XYou can prefix this command with a count
Xof the number of cells on the current row to clear.  The current column is
Xused if column recalculation order is set.
XCells cleared with this command may be recalled
Xwith any of the
X.I pull
Xcommands (see below).
X.\" ----------
X.TP
X.B m
XMark a cell to be used as the source for the
X.I copy
Xcommand.
X.\" ----------
X.TP
X.B c
XCopy the last marked cell to the current cell,
Xupdating row and column references in its numeric or string expression, if any.
X.\" ----------
X.TP
X.B +
XIf not in numeric mode, add the current numeric argument (default 1)
Xto the value of the current cell.  In numeric mode, ``+'' introduces a new
Xnumeric expression or value, the same as ``=''.
X.\" ----------
X.TP
X.B -
XIf not in numeric mode, subtract the current numeric argument (default 1)
Xfrom the value of the current cell.  In numeric mode, ``-'' introduces a new,
Xnegative, numeric expression or value, like ``=''.
X.\" ==========
X.SS "File Commands"
X.\" ----------
X\0 \" exactly one blank line (hard to get)
X.PD 0
X.TP
X.B G
XGet a new database from a file.
XIf encryption is enabled,
Xthe file is decrypted before it is loaded into the spreadsheet.
X.PD
X.\" ----------
X.TP
X.B P
XPut the current database into a file.
XIf encryption is enabled,
Xthe file is encrypted before it is saved.
X.\" ----------
X.TP
X.B W
XWrite a listing of the current database into a file
Xin a form that matches its appearance on the screen.
XThis differs from the
X.I Put
Xcommand in that its files are intended to be reloaded with
X.IR Get ,
Xwhile
X.I Write
Xproduces a file for people to look at.  Hidden rows or columns
Xare not shown when the data is printed.
X.\" ----------
X.TP
X.B T
XWrite a listing of the current database to a file,
Xbut include delimiters suitable for processing by the
X.IR tbl ,
X.IR LaTeX ,
Xor
X.I TeX
Xtable processors.
XThe delimiters are controlled by the
X.I tblstyle
Xoption.  See
X.I Set
Xabove.
XThe delimters are are a colon\ (:) for style
X.IR 0 or tbl
Xand an ampersand\ (&) for style
X.IR latex or tex .
X.\" ----------
X.PP
XWith the
X.IR Put ,
X.IR Write ,
Xand
X.I Table
Xcommands, the optional range argument writes a subset of the spreadsheet to
Xthe output file.
X.\" ----------
X.PP
XWith the
X.I Write
Xand
X.I Table
Xcommands, if you try to write to the last file used with the
X.I Get
Xor
X.I Put
Xcommands, or the file specified on the command line when
X.I pname
Xwas invoked, you are asked to confirm
Xthat the (potentially) dangerous operation is really what you want.
X.\" ----------
X.PP
XThe three output commands,
X.IR Put ,
X.IR Write ,
Xand
X.IR Table ,
Xcan pipe their (unencrypted only) output to a program.
XTo use this feature,
Xenter ``| program'' to the prompt asking for a filename.
XFor example, to redirect the output of the
X.I Write
Xcommand to the printer,
Xyou might enter ``| lpr -p''.
X.\" ----------
X.TP
X.B M
XMerge the database from the named file into the current database.
XValues and expressions defined in the named file
Xare read into the current spreadsheet
Xoverwriting the existing entries at matching cell locations.
X.\" ----------
X.TP
X.B R
XRun macros.
XSince
X.I pname
Xfiles are saved as ASCII files,
Xit is possible to use them as primitive macro definition files.
XThe
X.I Run
Xcommand makes this easier.
XIt's like the
X.I Merge
Xcommand,
Xbut prints a saved path name as the start of the filename to merge in.
XThe string to use is set with the
X.I Define
Xcommand.
XTo write macros, you must be familiar with the file format written by the
X.I Put
Xcommand.
XThis facility is still primitive and could be much improved.
X.\" ----------
X.TP
X.B D
XDefine a path for the
X.I Run
Xcommand to use.
X.\" ----------
X.PP
XAll file operations take a filename as the first argument
Xto the prompt on the top line.
XThe prompt supplies a " to aid in typing in the filename.
XThe filename can also be obtained from a cell's label string
Xor string expression.
XIn this case, delete the leading " with the backspace key
Xand enter a cell name such as
X.I a22
Xinstead.
XIf the resulting string starts with ``|'',
Xthe rest of the string is interpreted as a
X.SM UNIX
Xcommand, as above.
X.\" ==========
X.SS "Row and Column Commands"
X.\" ----------
XThese commands can be used on either rows or columns.
XThe second letter of the command is either a row designator
X(one of the characters
X.IR r ,
X.IR ^B ,
X.IR ^F ,
X.IR h ,
X.IR l )
Xor a column designator (one of
X.IR c ,
X.IR ^P ,
X.IR ^N ,
X.IR k ,
X.IR j ).
XA small menu lists the choices for the second letter
Xwhen you type the first letter of one of these commands.
XCommands which move or copy cells
Xalso modify the row and column references in affected cell expressions.
XThe references may be frozen by using the
X.I fixed
Xoperator or using the
X.I $
Xcharacter in the reference to the cell (see below).
X.\" ----------
X.TP
X.B "ir, ic"
XInsert a new row (column)
Xby moving the row (column) containing the cell cursor,
Xand all following rows (columns), down (right) one row (column).
XThe new row (column) is empty.
X.\" ----------
X.TP
X.B "ar, ac"
XAppend a new row (column) immediately following the current row (column).
XIt is initialized as a copy of the current one.
X.\" ----------
X.TP
X.B "dr, dc"
XDelete the current row (column).
X.\" ----------
X.TP
X.B "pr, pc, pm"
XPull deleted rows (columns) back into the spreadsheet.
XThe last deleted set of cells is put back into the spreadsheet
Xat the current location.
X.I pr
Xinserts enough rows to hold the data.
X.I pc
Xinserts enough columns to hold the data.
X.I pm
X(merge) does not insert rows or columns;
Xit overwrites the cells beginning at the current cell cursor location.
X.\" ----------
X.TP
X.B "vr, vc"
XRemove expressions from the affected rows (columns),
Xleaving only the values which were in the cells
Xbefore the command was executed.
X.\" ----------
X.TP
X.B "zr, zc"
XHide (``zap'') the current row (column).
XThis keeps a row (column) from being displayed but keeps it in the data base.
XThe status of the rows and columns is saved with the data base so hidden
Xrows and columns will be still
Xbe hidden when you reload the spreadsheet.  Hidden rows or columns are not
Xprinted by the
X.I W
Xcommand.
X.\" ----------
X.TP
X.B "sr, sc"
XShow hidden rows (columns).
XEnter a range of rows (columns) to be revealed.
XThe default is the first range of rows (columns) currently hidden.
XThis command ignores the repeat count, if any.
X.\" ----------
X.TP
X.B f
XSet the output format to be used
Xfor printing the numeric values in each cell in the current column.
XEnter two numbers:
Xthe total width in characters of the column,
Xand the number of digits to follow decimal points.
XValues are rounded off to the least significant digit displayed.
XThe total column width affects displays of strings as well as numbers.
XA preceding count can be used to affect more than one column.
XThis command has only a column version (no second letter).
X.\" ==========
X.SS "Range Commands"
X.\" ----------
XRange operations affect a rectangular region on the screen
Xdefined by the upper left and lower right cells in the region.
XAll of the commands in this class start with a slash;
Xthe second letter of the command indicates which command.
XA small menu lists the choices for the second letter when you type ``/''.
X.I pname
Xprompts for needed parameters for each command.
XPhrases surrounded by square brackets in the prompt are informational only
Xand may be erased with the backspace key.
X.\" ----------
X.PP
XPrompts requesting variable names may be satisfied
Xwith either an explicit variable name, such as
X.IR A10 ,
Xor with a variable name previously defined in a
X.I /d
Xcommand (see below).
XRange name prompts require either an explicit range such as
X.IR A10:B20 ,
Xor a range name previously defined with a
X.I /d
Xcommand.
XA default range shown in the second line
Xis used if you omit the range from the command or press the
X.SM TAB
Xkey (see below).
XThe default range can be changed by moving the cell cursor
Xvia the control commands
X.RI ( ^P ,
X.IR ^N ,
X.IR ^B ,
X.IR ^F )
Xor the arrow keys.
XThe cells in the default range are highlighted
X(using the terminal's standout mode, if available).
X.\" ----------
X.TP
X.B /x
XClear a range.
XCells cleared with this command may be recalled with any of the
X.I pull
Xcommands.
X.\" ----------
X.TP
X.B /v
XValues only.
XThis command removes the expressions from a range of cells,
Xleaving just the values of the expressions.
X.\" ----------
X.TP
X.B /c
XCopy a source range to a destination range.
XThe source and destination may be different sizes.
XThe result is always one or more full copies of the source.
XCopying a row to a row yields a row.
XCopying a column to a column yields a column.
XCopying a range to anything yields a range.
XCopying a row to a column or a column to a row yields a range
Xwith as many copies of the source as there are cells in the destination.
XThis command can be used to duplicate a cell through an arbitrary range
Xby making the source a single cell range such as
X.IR b20:b20 .
X.\" ----------
X.TP
X.B /f
XFill a range with constant values
Xstarting with a given value and increasing by a given increment.
XEach row is filled before moving on to the next row if row order
Xrecalculation is set.  Column order fills each column in the range
Xbefore moving on to the next column.
XThe start and increment numbers may be positive or negative.
XTo fill all cells with the same value, give an increment of zero.
X.\" ----------
X.TP
X.B /d
XUse this command to assign a symbolic name to a single cell
Xor a rectangular range of cells on the screen.
XThe parameters are the name, surrounded by "",
Xand either a single cell name such as
X.I A10
Xor a range such as
X.IR a1:b20 .
XNames defined in this fashion are used by the program in future prompts,
Xmay be entered in response to prompts requesting a cell or range name,
Xand are saved when the spreadsheet is saved with the
X.I Put
Xcommand.
XNames defined must be more than two alpha characters long
Xto differentiate them from a column names,
Xand must not have embedded special characters.
XNames may include the character ``_'' or numerals
Xas long as they occur after the first three alpha characters.
X.\" ----------
X.TP
X.B /s
XThis command lists (shows) the currently defined range names.
XIf there are no defined range names, then a message is given,
Xotherwise
Xit pipes output to
X.IR sort ,
Xthen to
X.IR less .
XIf the environment variable PAGER is set, its value is used in place of
X.IR less.
X.\" ----------
X.TP
X.B /u
XUse this command to undefine a previously defined range name.
X.\" ==========
X.SS "Miscellaneous Commands"
X.\" ----------
X\0 \" exactly one blank line (hard to get)
X.PD 0
X.TP
X.B Q
X.TP
X.B q
X.TP
X.B ^C
XExit from
X.IR pname .
XIf you made any changes since the last
X.I Get
Xor
X.IR Put ,
X.I pname
Xasks about saving your data before exiting.
X.PD
X.\" ----------
X.TP
X.B ^G
X.PD 0
X.TP
X.B ESC
XAbort entry of the current command.
X.PD
X.\" ----------
X.TP
X.B ?
XEnter an interactive help facility.  Lets you look up brief
Xsummaries of the main features of the program.  The help facility is
Xstructured like this manual page so it is easy to find more
Xinformation on a particular topic.
X.\" ----------
X.TP
X.B !
XShell escape.
X.I pname
Xprompts for a shell command to run.
XEnd the command line with the
X.SM RETURN
Xkey.
XIf the environment variable
X.SM SHELL
Xis defined, that shell is run.
XIf not, /bin/sh is used.
XGiving a null command line starts the shell in interactive mode.
XA second ``!'' repeats the previous command.
X.\" ----------
X.TP
X.B ^L
XRedraw the screen.
X.\" ----------
X.TP
X.B ^R
XRedraw the screen with special highlighting of cells to be filled in.
XThis is useful for finding values you need to provide or update
Xin a form with which you aren't familiar
Xor of which you have forgotten the details.
X
XIt's also useful for checking a form you are creating.
XAll cells which contain constant numeric values
X(not the result of a numeric expression)
Xare highlighted temporarily,
Xuntil the next screen change, however minor.
XTo avoid ambiguity,
Xthe current range (if any) and current cell are not highlighted.
X.\" ----------
X.TP
X.B ^X
XThis command is similar to
X.IR ^R ,
Xbut highlights cells which have expressions.
XIt also displays the expressions in the highlighted cells
Xas left-flushed strings,
Xinstead of the numeric values and/or label strings of those cells.
XThis command makes it easier to check expressions,
Xat least when they fit in their cells or the following cell(s) are blank
Xso the expressions can slop over (like label strings).
XIn the latter case, the slop over is not cleared on the next screen update,
Xso you may want to type
X.I ^L
Xafter the
X.I ^X
Xin order to clean up the screen.
X.\" ----------
X.TP
X.B @
XRecalculates the spreadsheet.
X.\" ----------
X.TP
X.B ^V
XType, in the command line, the name of the current cell
X(the one at the cell cursor).
XThis is useful when entering expressions
Xwhich refer to other cells in the table.
X.\" ----------
X.TP
X.B ^W
XType, in the command line, the expression attached to the current cell.
XIf there is none, the result is ``?''.
X.\" ----------
X.TP
X.B ^A
XType, in the command line, the numeric value of the current cell, if any.
X.\" ----------
X.PP
XThe
X.IR ^V ,
X.IR ^W ,
Xand
X.I ^A
Xcommands only work when the character cursor
Xis on the command line and beyond the first character.
X.\" ----------
X.TP
X.B TAB
XWhen the character cursor is on the top line,
Xdefines a range of cells via the cursor control commands or the arrow keys.
XThe range is highlighted,
Xstarts at the cell where you typed
X.SM TAB,
Xand continues through the current cell cursor.
XPressing
X.SM TAB
Xagain causes the highlighted range to be entered into the command line
Xand the highlighting to be turned off.
XThis is most useful for defining ranges to functions such as
X.IR @sum ().
XPressing ``)'' acts just like typing the
X.SM TAB
Xkey the second time and adds the closing ``)''.
XNote that when you give a range command,
Xyou don't need to press the first
X.SM TAB
Xto begin defining a range starting with the current cell.
X.\" ==========
X.SS "Variable Names"
X.\" ----------
XNormally, a variable name is just the name of a cell, such as
X.IR K20 .
XThe value is the numeric or string value of the cell,
Xaccording to context.
X.\" ----------
X.PP
XWhen a cell's expression (formula) is copied to another location via
X.I copy
Xor
X.IR range-copy ,
Xvariable references are by default offset by the amount the formula moved.
XThis allows the new formula to work on new data.
XIf cell references are not to change,
Xyou can either use the
X.I fixed
Xoperator (see below),
Xor one of the following variations on the cell name.
X.\" ----------
X.TP
X.I K20
XReferences cell
X.IR K20 ;
Xthe reference changes when the formula is copied.
X.\" ----------
X.TP
X.BI $ K $ 20
XAlways refers to cell
X.IR K20 ;
Xthe reference stays fixed when the formula is copied.
X.\" ----------
X.TP
X.BI $ K20
XKeeps the column fixed at column K;
Xthe row is free to vary.
X.\" ----------
X.TP
X.IB K $ 20
XSimilarly, this fixes the row and allows the column to vary.
X.\" ----------
X.PP
XThese conventions also hold on defined ranges.
XRange references vary when formulas containing them are copied.
XIf the range is defined with fixed variable references,
Xthe references do not change.
X.\" ----------
X.TP
X.B fixed
XTo make a variable not change automatically when a cell moves,
Xput the word
X.I fixed
Xin front of the reference, for example:
XB1 \(** fixed C3.
X.\" ==========
X.SS "Numeric Expressions"
X.\" ----------
XNumeric expressions used with the ``=''
Xand
X.I e
Xcommands have a fairly conventional syntax.
XTerms may be
Xconstants,
Xvariable names,
Xparenthesized expressions,
Xand negated terms.
XRanges may be operated upon with range functions such as sum
X.RI ( @sum ())
Xand average
X.RI ( @avg ()).
XTerms may be combined using binary operators.
X.\" ----------
X.TP
X.BR \- e
XNegation.
X.\" ----------
X.TP
X.RB e + e
XAddition.
X.\" ----------
X.TP
X.RB e \- e
XSubtraction.
X.\" ----------
X.TP
X.RB e \(** e
XMultiplication.
X.\" ----------
X.TP
X.RB e / e
XDivision.
X.\" ----------
X.TP
X.RB e1 % e2
Xe1 mod e2.
X.\" ----------
X.TP
X.RB e ^ e
XExponentiation.
X.\" ----------
X.TP
X.RB e < e
X.PD 0
X.TP
X.RB e <= e
X.TP
X.RB e = e
X.TP
X.RB e != e
X.TP
X.RB e >= e
X.TP
X.RB e > e
XRelationals:
Xtrue (1) if and only if the indicated relation holds,
Xelse false (0).
XNote that ``<='', ``!='', and ``>=''
Xare converted to their ``~()'' equivalents.
X.PD
X.\" ----------
X.TP
X.BR ~ e
XBoolean operator
X.SM NOT.
X.\" ----------
X.TP
X.RB e & e
XBoolean operator
X.SM AND.
X.\" ----------
X.TP
X.RB e | e
XBoolean operator
X.SM OR.
X.\" ----------
X.TP
X.RB @if (e, e, e)
X.PD 0
X.TP
X.RB e ? e : e
XConditional:
XIf the first expression is true then the value of the second is returned,
Xotherwise the value of the third.
X.\" ----------
X.PP
XOperator precedence from highest to lowest is:
X.PP
X.nf
X.RS
X\-, ~
X^
X\(**, /
X+, \-
X<, <=, =, !=, >=, >
X&
X|
X?:
X.RE
X.fi
X.\" ==========
X.SS "Built-in Range Functions"
X.\" ----------
XThese functions return numeric values.
X.\" ----------
X.TP 18
X.BR @sum (r)
XSum all valid (nonblank) entries in the region
Xwhose two corners are defined by the two variable names (e.g.
X.IR c5:e14 )
Xor the range name specified.
X.\" ----------
X.TP 18
X.BR @prod (r)
XMultiply together all valid (nonblank) entries in the specified region.
X.\" ----------
X.TP 18
X.BR @avg (r)
XAverage all valid (nonblank) entries in the specified region.
X.\" ----------
X.TP 18
X.BR @count (r)
XCount all valid (nonblank) entries in the specified region.
X.\" ----------
X.TP 18
X.BR @max (r)
XReturn the maximum value in the specified region.  See also the multi argument
Xversion of
X.I @max
Xbelow.
X.\" ----------
X.TP 18
X.BR @min (r)
XReturn the minimum value in the specified region.  See also the multi argument
Xversion of
X.I @min
Xbelow.
X.\" ----------
X.TP 18
X.BR @stddev (r)
XReturn the sample standard deviation of the cells in the specified region.
X.\" ----------
X.TP 18
X.BR @lookup (e,r)
X.PD 0
X.TP 18
X.BR @lookup (se,r)
X.PD
XEvaluates the expression then searches through the range
X.I r
Xfor a matching value.
XThe range should be either a single row or a single column.
XThe expression can be either a string
Xexpression or a numeric expression.  If it is a numeric expression,
Xthe range is searched for the the last value less than or equal to
X.IR e .
XIf the expression is a string expression, the string portions
Xof the cells in the range are searched for an exact string match.
XThe value returned is the numeric value from the next row and the same
Xcolumn as the match, if the range was a single row, or the value from
Xthe next column and the same row as the match if the range was a single
Xcolumn.
X.\" ----------
X.TP 18
X.BR @hlookup (e,r,n)
X.PD 0
X.TP 18
X.BR @hlookup (se,r,n)
X.PD
XEvaluates the expression then searches through the first row in the range
X.I r
Xfor a matching value.
XThe expression can be either a string
Xexpression or a numeric expression.  If it is a numeric expression,
Xthe row is searched for the the last value less than or equal to
X.IR e .
XIf the expression is a string expression, the string portions
Xof the cells in the row are searched for an exact string match.
XThe value returned is the numeric value from the same column
X.I n
Xrows below the match.
X.\" ----------
X.TP 18
X.BR @vlookup (e,r,n)
X.PD 0
X.TP 18
X.BR @vlookup (se,r,n)
X.PD
XEvaluates the expression then searches through the first column in the range
X.I r
Xfor a matching value.
XThe expression can be either a string
Xexpression or a numeric expression.  If it is a numeric expression,
Xthe column is searched for the the last value less than or equal to
X.IR e .
XIf the expression is a string expression, the string portions
Xof the cells in the column are searched for an exact string match.
XThe value returned is the numeric value from the same row
X.I n
Xcolumns to the right of the match.
X.\" ----------
X.TP 18
X.BR @index (e,r)
XUse the value of the expression
X.I e
Xto index into
Xthe range
X.IR r .
XThe numeric value at that position is returned.
XThe value 1 selects the first item in the range,
X2 selects the second item, etc.
X.I R
Xshould be either a single row or a single
Xcolumn.
X.\" ----------
X.TP 18
X.BR @stindex (e,r)
XUse the value of
X.I e
Xto index into
Xthe range
X.IR r .
XThe string value at that position is returned.
XThe value 1 selects the first item in the range,
X2 selects the second item, etc.
XThe range should be either a single row or a single
Xcolumn.
X.\" ==========
X.SS "Built-in Numeric Functions"
X.\" ----------
XAll of these functions operate on floating point numbers (doubles)
Xand return numeric values.
XMost of them are standard system functions more fully described in
X.IR math (3).
XThe trig functions operate with angles in radians.
X.\" ----------
X.TP 18
X.BR @sqrt (e)
XReturn the square root of
X.IR e .
X.\" ----------
X.TP 18
X.BR @exp (e)
XReturn the exponential function of
X.IR e .
X.\" ----------
X.TP 18
X.BR @ln (e)
XReturn the natural logarithm of
X.IR e .
X.\" ----------
X.TP 18
X.BR @log (e)
XReturn the base 10 logarithm of
X.IR e .
X.\" ----------
X.TP 18
X.BR @floor (e)
XReturn the largest integer not greater than
X.IR e .
X.\" ----------
X.TP 18
X.BR @ceil (e)
XReturn the smallest integer not less than
X.IR e .
X.\" ----------
X.TP 18
X.BR @rnd (e)
XRound
X.I e
Xto the nearest integer.
X.TP 18
X.BR @round (e,n)
XRound
X.I e
Xto
X.I n
Xdecimal places.
X.\" ----------
X.TP 18
X.BR @abs (e)
X.PD 0
X.TP 18
X.BR @fabs (e)
XReturn the absolute value of
X.IR e .
X.\" ----------
X.TP 18
X.BR @pow (e1,e2)
XReturn
X.I e1
Xraised to the power of
X.IR e2 .
X.\" ----------
X.TP 18
X.BR @hypot (e1,e2)
XReturn sqrt(e1\(**e1+e2\(**e2), taking precautions against unwarranted
Xoverflows.
X.\" ----------
X.TP 18
X.B pi
XA constant quite close to pi.
X.\" ----------
X.TP 18
X.BR @dtr (e)
XConvert
X.I e
Xin degrees to radians.
X.\" ----------
X.TP 18
X.BR @rtd (e)
XConvert
X.I e
Xin radians to degrees.
X.\" ----------
X.TP 18
X.BR @sin (e)
X.PD 0
X.TP 18
X.BR @cos (e)
X.TP 18
X.BR @tan (e)
XReturn trigonometric functions of radian arguments.
XThe magnitude of the arguments are not checked to assure meaningful results.
X.PD
X.\" ----------
X.TP 18
X.BR @asin (e)
XReturn the arc sine of
X.I e
Xin the range -pi/2 to pi/2.
X.\" ----------
X.TP 18
X.BR @acos (e)
XReturn the arc cosine of
X.I e
Xin the range 0 to pi.
X.\" ----------
X.TP 18
X.BR @atan (e)
XReturn the arc tangent of
X.I e
Xin the range -pi/2 to pi/2.
X.\" ----------
X.TP 18
X.BR @atan2 (e1,e2)
XReturns the arc tangent of
X.IR e1 / e2
Xin the range -pi to pi.
X.\" ----------
X.TP 18
X.BR @max (e1,e2,...)
XReturn the maximum of the values of the expressions.  Two or more expressions
Xmay be specified.  See also the range version of
X.I @max
Xabove.
X.\" ----------
X.TP 18
X.BR @min (e1,e2,...)
XReturn the minimum of the values of the expressions.  Two or more expressions
Xmay be specified.  See also the range version of
X.I @min
Xabove.
X.\" ----------
X.TP 18
X.BR @ston (se)
XConvert string expression
X.I se
Xto a numeric value.
X.\" ----------
X.TP 18
X.BR @eqs (se1,se2)
XReturn 1 if string expression
X.I se1
Xhas the same value as string expression
X.IR se2 ,
X0 otherwise.
X.\" ----------
X.TP 18
X.BR @nval (se,e)
XReturn the numeric value of a cell selected by name.
XString expression
X.I se
Xmust evaluate to a column name (``A''-``AE'') and
X.I e
Xmust evaluate to a row number (0-199).
XIf
X.I se
Xor
X.I e
Xis out of bounds, or the cell has no numeric value, the result is 0.
XYou can use this for simple table lookups.
XBe sure the table doesn't move unexpectedly!
XSee also
X.IR @sval ()
Xbelow.
X.\" ==========
X.SS "String Expressions"
X.\" ----------
XString expressions are made up of constant strings
X(characters surrounded by double quotation marks),
Xvariables
X(cell names, which refer to the cells's label strings or expressions),
Xand string functions.
XNote that string expressions are only allowed
Xwhen entering a cell's label string, not its numeric part.
XAlso note that string expression results may be left or right flushed,
Xaccording to the type of the cell's string label.
X.\" ----------
X.TP
X.B #
XConcatenate strings.
XFor example, the string expression
X.IP ""
X    A0 # "zy dog"
X.IP ""
Xdisplays the string ``the lazy dog'' in the cell if the value of
X.IR A0 's
Xstring is ``the la''.
X.\" ==========
X.SS "Built-in String Functions"
X.\" ----------
X\0 \" exactly one blank line (hard to get)
X.PD 0
X.TP 18
X.BR @substr (se,e1,e2)
XExtract and return from string expression
X.I se
Xthe substring indexed by character number
X.I e1
Xthrough character number
X.I e2
X(defaults to the size of
X.I se
Xif beyond the end of it).
XIf
X.I e1
Xis less than 1 or greater than
X.IR e2 ,
Xthe result is the null string.
XFor example,
X.PD
X.IP ""
X    @substr ("Nice jacket", 4, 7)
X.IP ""
Xreturns the string ``e jac''.
X.\" ----------
X.TP 18
X.BR @fmt (se,e)
XConvert a number to a string.
XThe argument
X.I se
Xmust be a valid
X.IR printf (3)
Xformat string.
X.I e
Xis converted according to the standard rules.
XFor example, the expression
X.IP ""
X    @fmt ("\(**\(**%6.3f\(**\(**", 10.5)
X.IP ""
Xyields the string ``\(**\(**10.500\(**\(**''.
X.I e
Xis a double, so applicable formats are e, E, f, g, and G.
XTry ``%g'' as a starting point.
X.\" ----------
X.TP 18
X.BR @sval (se,e)
XReturn the string value of a cell selected by name.
XString expression
X.I se
Xmust evaluate to a column name (``A''-``AE'') and
X.I e
Xmust evaluate to a row number (0-199).
XIf
X.I se
Xor
X.I e
Xis out of bounds, or the cell has no string value,
Xthe result is the null string.
XYou can use this for simple table lookups.
XBe sure the table doesn't move unexpectedly!
X.\" ----------
X.TP 18
X.BR @ext (se,e)
XCall an external function (program or script).
XThe purpose is to allow arbitrary functions on values,
Xe.g. table lookups and interpolations.
XString expression
X.I se
Xis a command or command line to call with
X.IR popen (3).
XThe value of
X.I e
Xis converted to a string and appended to the command line as an argument.
XThe result of
X.IR @ext ()
Xis a string:
Xthe first line printed to standard output by the command.
XThe command should emit exactly one output line.
XAdditional output, or output to standard error, messes up the screen.
X.IR @ext ()
Xreturns a null string and prints an appropriate warning
Xif external functions are disabled,
X.I se
Xis null, or the attempt to run the command fails.
X.IP ""
XExternal functions can be slow to run,
Xand if enabled are called at each screen update,
Xso they are disabled by default.
XYou can enable them with
X.I ^T
Xwhen you really want them called.
X.IP ""
XA simple example:
X.IP ""
X    @ext ("echo", a1)
X.IP ""
XYou can use
X.IR @ston ()
Xto convert the
X.IR @ext ()
Xresult back to a number.
XFor example:
X.IP ""
X    @ston (@ext ("form.sc.ext", a9 + b9))
X.IP ""
XNote that you can built a command line (including more argument values)
Xfrom a string expression with concatenation.
XYou can also "hide" the second argument by ending the command line
X(first argument) with `` #'' (shell comment).
X.\" ==========
X.SS "Built-in Financial Functions"
X.\" ----------
XFinancial functions compute the mortgage (or loan) payment, future value,
Xand the present value functions.  Each accepts
Xthree arguments, an amount, a rate of interest (per period), and
Xthe number of periods.
XThese functions are the same as those commonly found in other spreadsheets
Xand financial calculators
X.\" ----------
X.TP 18
X.BR @pmt (e1,e2,e3)
X.IR @pmt (60000,.01,360)
Xcomputes the monthly payments for a $60000 mortgage at 12% annual interest
X(.01 per month) for 30 years (360 months).
X.\" ----------
X.TP 18
X.BR @fv (e1,e2,e3)
X.IR @fv (100,.005,36)
Xcomputes the future value for of 36 monthly payments of $100 at 6%
Xinterest (.005 per month).  It answers the question: "How much
Xwill I have in 36 months if I deposit $100 per month in a savings
Xaccount paying 6% interest compounded monthly?"
X.\" ----------
X.TP 18
X.BR @pv (e1,e2,e3)
X.IR @pv (1000,.015,36)
Xcomputes the present value of an a ordinary annuity of
X36 monthly payments of $1000 at 18% annual interest.
XIt answers the question: "How much can I borrow at 18% for 30 years
Xif I pay $1000 per month?"
X.\" ==========
X.SS "Built-in Date and Time Functions"
X.\" ----------
XTime for
X.I pname
Xfollows the system standard:
Xthe number of seconds since 1970.
XAll date and time functions except
X.IR @date ()
Xreturn numbers, not strings.
X.\" ----------
X.TP 18
X.B @now
XReturn the current time encoded
Xas the number of seconds since the beginning of the
Xepoch (December 31, 1969, midnight, GMT.)
X.\" ----------
X.TP 18
X.BR @dts (e1,e2,e3)
X.IR @dts (9,14,1988)
Xconverts the date September 14, 1988
Xto the number of seconds from the epoch
Xto the first second of 9/14/88, local time.
XFor example,
X.IR @date ( @dts (12,14,1976))
Xyields
X.IP ""
X.I "    Tue Dec 14 00:00:00 1976"
X.IP ""
XThe month should be range from  1 to 12, the day should range from
X1 to the number of days in the specified month, and the year should
Xrange from 1970 to 1999.
X.\" ----------
X.TP 18
X.BR @tts (e1,e2,e3)
X.IR @tts (8,20,45)
Xconverts the time 8:40:45 to the number of seconds since
Xmidnight, the night before.  The hour should range from 0 to 23;
Xthe minutes and seconds should range from 0 to 59.
X.\" ----------
X.PP
XThe following functions take the time in seconds
X(e.g. from
X.IR @now )
Xas an argument and return the specified value.
XThe functions all convert from GMT to local time.
X.\" ----------
X.TP 18
X.BR @date (e)
XConvert the time in seconds to a date string
X24 characters long in the following form:
X.IP ""
X.I "    Sun Sep 16 01:03:52 1973"
X.IP ""
XNote that you can extract parts of this fixed-format string with
X.IR @substr ().
X.\" ----------
X.TP 18
X.BR @year (e)
XReturn the year.
XValid years begin with 1970.
XThe last legal year is system dependent.
X.\" ----------
X.TP 18
X.BR @month (e)
XReturn the month, encoded as 1 (January) to 12 (December).
X.\" ----------
X.TP 18
X.BR @day (e)
XReturn the day of the month, encoded as 1 to 31.
X.\" ----------
X.TP 18
X.BR @hour (e)
XReturn the number of hours since midnight, encoded as 0 to 23.
X.\" ----------
X.TP 18
X.BR @minute (e)
XReturn the number of minutes since the last full hour, encoded as 0 to 59.
X.\" ----------
X.TP 18
X.BR @second (e)
XReturn the number of seconds since the last full minute, encoded as 0 to 59.
X.\" ==========
X.SS "Spreadsheet Update"
X.\" ----------
XRe-evaluation of spreadsheet expressions
Xis done by row or by column depending on the selected calculation order.
XEvaluation is repeated up to
X.I iterations
Xtimes for each update if necessary,
Xso forward references usually work as expected.  See
X.I set
Xabove.
XIf stability is not reached after ten iterations,
Xa warning is printed.
XThis is usually due to a long series of forward references,
Xor to unstable cyclic references (for example, set
X.IR A0 's
Xexpression to ``A0+1'').
X.\" ==========
X.SH SEE ALSO
Xbc(1), dc(1), crypt(1), ppname(1)
X.\" ==========
X.SH BUGS
XTop-to-bottom, left-to-right evaluation of expressions is silly.
XA proper following of the dependency graph
Xwith (perhaps) recourse to relaxation should be implemented.
X.\" ----------
X.PP
XEditing is crude.
XAll you can do is backspace over and retype text to be altered.
XThere is no easy way to switch a leftstring to a rightstring or vice versa.
XOf course, you can always write the spreadsheet to a file with
X.IR Put ,
Xedit it by calling an editor on the file with ``!'',
Xand read it back with
X.I Get
X-- if you are comfortable editing spreadsheet files.
X.\" ----------
X.PP
XOnly one previous value is saved from any call of
X.IR @ext ().
XIf it is used more than once in a spreadsheet
Xand external functions are enabled and later disabled,
Xthe last returned value pops up in several places.
X.\" ----------
X.PP
XOn some systems,
Xif the cell cursor is in column 0 with topline enabled
X(so the current cell is highlighted),
Xor if any cell in column 0 is highlighted,
Xthe corresponding row number gets displayed and then blanked
Xduring a screen refresh.
XThis looks like a bug in
X.IR curses .
X.\" ----------
X.PP
XMany commands give no indication (a message or beep) if they have null effect.
XSome should give confirmation of their action, but they don't.
END_OF_FILE
  if test 45229 -ne `wc -c <'sc.doc'`; then
    echo shar: \"'sc.doc'\" unpacked with wrong size!
  fi
  # end of 'sc.doc'
fi
echo shar: End of archive 1 \(of 6\).
cp /dev/null ark1isdone
MISSING=""
for I in 1 2 3 4 5 6 ; do
    if test ! -f ark${I}isdone ; then
    MISSING="${MISSING} ${I}"
    fi
done
if test "${MISSING}" = "" ; then
    echo You have unpacked all 6 archives.
    rm -f ark[1-9]isdone
else
    echo You still must unpack the following archives:
    echo "        " ${MISSING}
fi
exit 0
exit 0 # Just in case...